.TH OPTIPNG 1 "2009-May-18" "OptiPNG version 0.6.3"

.SH NAME
.B OptiPNG
\- Advanced optimization program for
.B Portable Network Graphics (PNG)

.SH SYNOPSIS
.B optipng
[\fB\-?\fP | \fB\-h\fP | \fB\-help\fP]
.br
.B optipng
[\fIoptions...\fP] \fIfiles...\fP

.SH DESCRIPTION
The
.B OptiPNG
program shall attempt to \fIoptimize\fP PNG files, i.e. reduce their size to
a minimum, without losing any information. In addition, this program shall
perform a suite of auxiliary functions like integrity checks, metadata recovery
and pixmap-to-PNG conversion.
.P
The optimization attempts are not guaranteed to succeed. Valid PNG files that
cannot be optimized by this program are normally left intact; their size will
not grow. The user may request to override this default behavior.

.SH FILES
The input files are raster image files encoded either in PNG format (the native
format), or in an external format. The currently supported external formats are
GIF, BMP, PNM and TIFF.
.P
.B OptiPNG
processes each image file given in the command line as follows:
.P
\- If it is in PNG format:
.IP
Attempt to optimize the given file in-place. If optimization is successful, or
if the option \fB\-force\fP is in effect, replace the original file with its
optimized version. The original file is backed up if the option \fB\-keep\fP
is in effect.
.P
\- If it is in an external format:
.IP
Create an optimized PNG version of the given file. The output file name is
composed from the original file name and the \fC.png\fP extension.

.SH OPTIONS
.SS "General options"
.TP
\fB-?\fP, \fB\-h\fP, \fB\-help\fP
Show a complete summary of options.
.TP
\fB\-o\fP \fIlevel\fP
Select the optimization level.
.br
Use \fB\-o0\fP to disable IDAT recompression trials. This option has no effect
on non-PNG input files.
.br
Use \fB\-o1\fP to enable a single IDAT recompression trial.
.br
Use a higher \fIlevel\fP to enable more trials
(the higher the \fIlevel\fP, the more trials).
.br
The behavior and the default value of this option may change across different
program versions. Use option \fB\-h\fP to see the details pertaining to your
specific version.
.TP
\fB\-dir\fP \fIdirectory\fP
Write output file(s) to \fIdirectory\fP.
.TP
\fB\-fix\fP
Enable error recovery. This option has no effect on valid input files.
.br
The program will spend a reasonable amount of effort to recover as much data as
possible, without increasing the output file size, but the success cannot be
generally guaranteed. The program may even increase the file size, e.g., by
reconstructing missing critical data. Under this option, integrity shall take
precedence over file size.
.br
When this option is not used, the invalid input files are left unprocessed.
.TP
\fB\-force\fP
Enforce writing of a new output file.
.br
Use this option to override the program's decision not to write such file,
e.g. when the PNG input is digitally signed (using dSIG), or when the PNG
output becomes larger than the PNG input.
.TP
\fB\-keep\fP
Keep a backup of the modified file(s).
.br
The files that use the backup names prior to the program execution are
\fInot\fP overwritten.
.TP
\fB\-log\fP \fIfile\fP
Log messages to \fIfile\fP.
For safety reasons, \fIfile\fP must have the extension \fC.log\fP.
.TP
\fB\-out\fP \fIfile\fP
Write output file to \fIfile\fP.
The command line must contain exactly one input file.
.TP
\fB\-preserve\fP
Preserve file attributes (time stamps, file access rights, etc.) where
applicable.
.TP
\fB\-quiet\fP
Run in quiet mode.
.br
These messages are still written to the log file if the option \fB\-log\fP is
in effect.
.TP
\fB\-simulate\fP
Run in simulation mode: perform the trials, but do not create output files.
.TP
\fB\-snip\fP
Cut one image out of multi-image, animation or video file(s).
.br
Depending on the input format, this may be either the first or the most
relevant (e.g. the largest) image.
.TP
\fB\-v\fP
Enable the options \fB\-verbose\fP and \fB\-version\fP.
.TP
\fB\-verbose\fP
Run in verbose mode.
.TP
\fB\-version\fP
Show copyright, version and build info.
.TP
\fB\-\-\fP
Stop option switch parsing.
.SS "PNG encoding and optimization options"
.TP
\fB\-f\fP \fIfilters\fP
Select the PNG delta filters.
.br
The \fIfilters\fP argument is specified as a rangeset (e.g. \fB\-f0\-5\fP),
and the default \fIfilters\fP value depends on the optimization level set by
the option \fB\-o\fP.
.br
The filter values 0, 1, 2, 3 and 4 indicate static filtering, and correspond to
the standard PNG filter codes (\fINone\fP, \fILeft\fP, \fIUp\fP, \fIAverage\fP
and \fIPaeth\fP, respectively). The filter value 5 indicates adaptive filtering,
whose effect is defined by the \fBlibpng\fP(3) library used by \fBOptiPNG\fP.
.TP
\fB\-full\fP
Produce a full report on IDAT.
This option might slow down the trials.
.TP
\fB\-i\fP \fItype\fP
Select the interlace type (0\-1).
.br
Use \fB\-i0\fP to produce a non-interlaced output.
.br
Use \fB\-i1\fP to produce an interlaced (\fIAdam7\fP) output.
.br
By default, the output will have the same interlace type as the input.
.TP
\fB\-nb\fP
Do not apply bit depth reduction.
.TP
\fB\-nc\fP
Do not apply color type reduction.
.TP
\fB\-np\fP
Do not apply palette reduction.
.TP
\fB\-nz\fP
Do not perform IDAT recompression (also disable reductions).
.TP
\fB\-zc\fP \fIlevels\fP
Select the zlib compression levels used in IDAT compression.
.br
The \fIlevels\fP argument is specified as a rangeset (e.g. \fB\-zc6\-9\fP),
and the default \fIlevels\fP value depends on the optimization level set by
the option \fB\-o\fP.
.br
The effect of this option is defined by the \fBzlib\fP(3) library used by
\fBOptiPNG\fP.
.TP
\fB\-zm\fP \fIlevels\fP
Select the zlib memory levels used in IDAT compression.
.br
The \fIlevels\fP argument is specified as a rangeset (e.g. \fB-zm8\-9\fP),
and the default \fIlevels\fP value depends on the optimization level set by
the option \fB\-o\fP.
.br
The effect of this option is defined by the \fBzlib\fP(3) library used by
\fBOptiPNG\fP.
.TP
\fB\-zs\fP \fIstrategies\fP
Select the zlib compression strategies used in IDAT compression.
.br
The \fIstrategies\fP argument is specified as a rangeset (e.g. \fB-zs0\-3\fP),
and the default \fIstrategies\fP value depends on the optimization level set by
the option \fB\-o\fP.
.br
The effect of this option is defined by the \fBzlib\fP(3) library used by
\fBOptiPNG\fP.
.TP
\fB\-zw\fP \fIsize\fP
Select the zlib window size (32k,16k,8k,4k,2k,1k,512,256) used in IDAT
compression.
.br
The \fIsize\fP argument can be specified either in bytes (e.g. 16384) or
kilobytes (e.g. 16k). The default \fIsize\fP value is set to the lowest
window size that yields an IDAT output as big as if yielded by the value 32768.
.br
The effect of this option is defined by the \fBzlib\fP(3) library used by
\fBOptiPNG\fP.
.SS "Notes"
Options may come in any order (except for \fB\-\-\fP), before, after, or
alternating with file names. Option names are case-insensitive and may be
abbreviated to their shortest unique prefix.
.P
Some options may have arguments that follow the option name, separated by
whitespace or the equal sign ('\fB=\fP'). If the option argument is a number
or a rangeset, the separator may be omitted. For example:
.IP
\fB\-out\fP \fCnewfile.png\fP\h'2'<=>\h'2'\fB\-out=\fP\fCnewfile.png\fP
.br
\fB\-o3\fP\h'2'<=>\h'2'\fB\-o\ 3\fP\h'2'<=>\h'2'\fB\-o=3\fP
.br
\fB\-f0,3\-5\fP\h'2'<=>\h'2'\fB\-f\ 0,3\-5\fP\h'2'<=>\h'2'\fB\-f=0,3\-5\fP
.P
Rangeset arguments are cumulative; e.g.
.IP
\fB\-f0 \-f3\-5\fP\h'2'<=>\h'2'\fB\-f0,3\-5\fP
.br
\fB\-zs0 \-zs1 \-zs2\-3\fP\h'2'<=>\h'2'\fB\-zs0,1,2,3\fP\h'2'<=>\h'2'\fB\-zs0\-3\fP

.SH "EXTENDED DESCRIPTION"
The PNG optimization algorithm consists of the following steps:
.TP
1.
Reduce the bit depth, the color type and the color palette of the image.
This step may reduce the size of the uncompressed image, which, indirectly, may
reduce the size of the compressed image (i.e. the size of the output PNG file).
.TP
2.
Run a suite of compression methods and strategies and select the compression
parameters that yield the smallest output file.
.TP
3.
Store all IDAT contents into a single chunk, eliminating the overhead
incurred by repeated IDAT headers and CRCs.
.TP
4.
Set the zlib window size inside IDAT to a mininum that does not affect the
compression ratio, reducing the memory requirements of PNG decoders.
.P
Not all of the above steps need to be executed. The behavior depends on the
actual input files and user options.
.P
Step 1 may be customized via the no-reduce options \fB\-nb\fP, \fB\-nc\fP and
\fB\-np\fP. Step 2 may be customized via the \fB\-o\fP option, and may be
fine-tuned via the options \fB\-zc\fP, \fB\-zm\fP, \fB\-zs\fP and \fB\-zw\fP.
Step 3 is always executed; for example, even though IDAT recompression is
disabled under \fB\-o0\fP, all IDAT chunks from the input are concatenated into
a single IDAT chunk in the output. Step 4 is executed only if a new IDAT is
being created, and may be fine-tuned via the option \fB\-zw\fP.
.P
Extremely exhaustive searches are not generally expected to yield significant
improvements in compression ratio, and are recommended to advanced users only.

.SH EXAMPLES
\fCoptipng file1.png file2.gif file3.tif\fP
.P
\fCoptipng \-o5 file1.png file2.gif file3.tif\fP
.P
\fCoptipng \-i1 \-o7 \-v \-full \-sim experiment.png \-log experiment.log\fP

.SH BUGS
Lossless image reductions are not completely implemented.
(This does NOT affect the integrity of the output files.)
Here are the missing pieces:
.IP
\- The color palette reductions are implemented only partially.
.br
\- The bit depth reductions below 8, for grayscale images, are not implemented
yet.
.P
TIFF support is limited to uncompressed, PNG-compatible (grayscale, RGB and
RGBA) images.
.P
Metadata is not imported from the external image formats.
.P
There is no support for pipes or streams.

.SH SEE ALSO
\fBpng\fP(5),
\fBlibpng\fP(3),
\fBzlib\fP(3),
\fBpngcrush\fP(1),
\fBpngrewrite\fP(1).
.PP
Glenn Randers-Pehrson et al.
\fIPortable Network Graphics (PNG) Specification, Second Edition\fP.
.br
W3C Recommendation 10 November 2003; ISO/IEC IS 15948:2003 (E).
.br
\fChttp://www.w3.org/TR/PNG/\fP

.SH AUTHOR
\fBOptiPNG\fP is written and maintained by Cosmin Truta.
.PP
This manual page was originally written by Nelson A. de Oliveira
for the Debian Project. It was later updated by Cosmin Truta,
and is now part of the \fBOptiPNG\fP distribution.
